home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / Amiga_Mail_Vol2 / Archives / Plain / so91.lha / FileName / filename.txt < prev    next >
Encoding:
Text File  |  1991-10-23  |  7.3 KB  |  168 lines
  1. (c)  Copyright 1991 Commodore-Amiga, Inc.   All rights reserved.
  2. The information contained herein is subject to change without notice,
  3. and is provided "as is" without warranty of any kind, either expressed
  4. or implied.  The entire risk as to the use of this information is
  5. assumed by the user.
  6.  
  7. The 2.0 Dos.library Path Name Handling Functions
  8.  
  9.  
  10. By Ewout Walraven
  11.  
  12.  
  13. When processing file names, it is often necessary to extract only a file
  14. name from a path or to generate an absolute path to a file.  The release
  15. 2.0 dos.library contains several routines designed to make this easier.
  16.  
  17. The FilePart() function takes a pointer to a file path and returns a
  18. pointer to the last part of the string (the part of the string that follows
  19. the last separator character, ``/'').  The last part of the string is
  20. normally a file or directory name.
  21.  
  22. UBYTE *FilePart(UBYTE *mypath);
  23.  
  24. In case mypath (from the prototype above) consists only of a file or
  25. directory name (like startup-sequence, s, or libs), FilePart() returns a
  26. pointer to the start of the string (a.k.a. the same value as mypath).
  27.  
  28. The PathPart() function returns a pointer to the last character in the path
  29. string that doesn't include the file name (usually the separator character
  30. ``/''):
  31.  
  32. UBYTE *PathPart(UBYTE *mypath);
  33.  
  34. If passed a pointer to the path string ``sys:s/startup-sequence'',
  35. PathPart() will return a pointer to  ``/startup-sequence''.  The
  36. application can then put a \0 where PathPart() points so that the original
  37. string has been shortened to a path part string.  In case mypath (from the
  38. above prototype) is only a file name, PathPart() returns a pointer to this
  39. file name (the same value as mypath).  This can confuse an application if
  40. it blindly expects PathPart() to return a path.  An application should make
  41. sure the pointer PathPart() returns is not the same pointer the application
  42. passed to the function.
  43.  
  44. Both FilePart() and PathPart() consider the initial colon of an absolute
  45. path name (a path starting with a volume/device/assign name) to be a
  46. special separator character, but PathPart() will not include the colon in
  47. the string it returns a pointer to.  For example, if passed the string
  48. ``ram:tmpfile'', PathPart() will return a pointer to the string ``tmpfile''.
  49.  
  50. Neither FilePart() nor PathPart() check the syntax of the path string
  51. passed to them, so if your application passes an invalid path to them, they
  52. will pass back equally invalid path fragments.  Also, they do not process
  53. any of the wildcard tokens, treating them as normal characters. The
  54. following chart summarizes the possible results of the FilePart() and
  55. PathPart() functions.  It assumes that the path supplied to the functions
  56. is valid.
  57.  
  58. wholepath is the path passed to FilePart() and PathPart(), pathpart is
  59. result of PathPart(), and filepart is the result of FilePart().
  60.  
  61. 1. If (wholepath != pathpart != filepart), then filepart points to the the
  62. file or directory name in wholepath and pathpart points to the '/' before
  63. the file or directory name in wholepath.  For example:
  64.  
  65.     wholepath: ``ram:t/tmpfile''
  66.     Filepart: ``tmpfile''
  67.     Pathpart: ``/tmpfile''
  68.  
  69.     wholepath: ``//t/tmpfile''
  70.     Filepart: ``tmpfile''
  71.     Pathpart: ``/tmpfile''
  72.  
  73. 2. If (wholepath != pathpart == filepart), then filepart and pathpart point
  74. to a file or a directory name preceded by a volume name or series of
  75. separator characters.  For example:
  76.  
  77.     wholepath: ``ram:tmpfile''
  78.     Filepart: ``tmpfile''
  79.     Pathpart: ``tmpfile''
  80.  
  81.     wholepath: ``//tmpfile''
  82.     Filepart: ``tmpfile''
  83.     Pathpart: ``tmpfile''
  84.  
  85. 3. If (wholepath == pathpart == filepart) then pathpart points to either a
  86. file or a directory name.  This name is not preceded by a volume name.
  87.  
  88.     wholepath: ``tmpfile''
  89.     Filepart: ``tmpfile''
  90.     Pathpart: ``tmpfile''
  91.  
  92. 4. If (pathpart[0] == 0), then path points to either "" (current
  93. directory), a series of separators (``/'', ``//'', ``:'', etc.), or a
  94. volume/device name.
  95.  
  96.     wholepath: ``////''
  97.     Filepart: ``''
  98.     Pathpart: ``''
  99.  
  100.     wholepath: ``ram:''
  101.     Filepart: ``''
  102.     Pathpart: ``''
  103.  
  104. The dos.library AddPart() function lets you append a file or directory name
  105. to the end of a (relative) path, inserting any necessary separator
  106. characters:
  107.  
  108. BOOL AddPart(UBYTE *mypathname, UBYTE *myfilename, ULONG mysize); AddPart()
  109. will add myfilename to the end of mypathname.  The mysize argument
  110. indicates how large the mypathname buffer is.  In case this buffer is too
  111. small, AppPart() returns FALSE and makes no changes to the buffer.  If
  112. myfilename is an absolute path, it will replace the current contents of the
  113. mypathname buffer.  If myfilename starts with a colon, AddPart() will
  114. generate a new path relative to the root of the volume/device in mypathname.
  115.  
  116. These functions are used in subsequent examples.  The Part.c example lets
  117. you view the results of these functions.  Taking a path and a file name as
  118. arguments, Path.c interprets the path, removes the file name (if part of)
  119. from the path and replaces the path's file name with the file name supplied
  120. in the argument list.
  121.  
  122. Another dos.library function called SplitName() makes it possible to
  123. extract individual volume/device, directory, or file names (referred to
  124. here as path components) from a path string:
  125.  
  126. WORD = SplitName(UBYTE *mypathname, UBYTE separatorchar, UBYTE *buffer,
  127.                  WORD oldposition, LONG buffersize);
  128.  
  129. SplitName() searches through the string mypathname for the separator
  130. character (separatorchar from the above prototype) starting at oldposition.
  131. As it is stepping through mypathname, SplitName() copies the characters it
  132. encounters from mypathname to the buffer, terminating the resulting string
  133. with a NULL.  It does not copy the separator character into the buffer.  If
  134. it finds the separator character, SplitName() returns the position of the
  135. character that follows the separator character.  This position can be used
  136. as the oldposition argument in subsequent calls to SplitName() to extract
  137. other path components from the same path.  If SplitName() does not find
  138. another separator character, it will return -1, although it will still copy
  139. characters from mypathname to buffer.  For example, if SplitName() was
  140. called with the following arguments:
  141.  
  142. mypathname = "ram:env/sys/win.pat"
  143. separatorchar = '/'
  144. oldposition = 8
  145. buffersize = 10
  146.  
  147. buffer would contain the NULL terminated string ``sys'' and SplitName()
  148. would return a value of 12.  If SplitName() was called again placing the
  149. return value of 12 into oldposition, buffer would contain the NULL
  150. terminated string ``win.pat'' and SplitName() would return a value of -1,
  151. as there are no separator characters in mypathname beyond the eleventh
  152. character.
  153.  
  154. If SplitName() runs out of room in the buffer, it will copy as much of the
  155. characters as it can fit (buffersize - 1) and will write a NULL into the
  156. last position in the buffer (actually, if a path component is followed by a
  157. separator character and the 2.04 version SplitName() runs out of room in
  158. the buffer, SplitName() will only copy (buffersize - 2) characters into the
  159. buffer.  This may be rectified in the future).  Also, if SplitName() runs
  160. out of room in the buffer and it finds another separator character, the
  161. position it returns will not be of the character that follows the separator
  162. character.  Instead, SplitName() will return the position of the actual
  163. separator character.
  164.  
  165. The Split.c example shows the behavior of this function.  The example takes
  166. two arguments, the path name to split up and the size of the destination
  167. buffer SplitName() should use for the path components.
  168.